home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl5 / Net / DBus / Annotation.pm next >
Encoding:
Perl POD Document  |  2008-02-20  |  2.7 KB  |  132 lines
  1. # -*- perl -*-
  2. #
  3. # Copyright (C) 2006 Daniel P. Berrange
  4. #
  5. # This program is free software; You can redistribute it and/or modify
  6. # it under the same terms as Perl itself. Either:
  7. #
  8. # a) the GNU General Public License as published by the Free
  9. #   Software Foundation; either version 2, or (at your option) any
  10. #   later version,
  11. #
  12. # or
  13. #
  14. # b) the "Artistic License"
  15. #
  16. # The file "COPYING" distributed along with this file provides full
  17. # details of the terms and conditions of the two licenses.
  18.  
  19. =pod
  20.  
  21. =head1 NAME
  22.  
  23. Net::DBus::Annotation - annotations for changing behaviour of APIs
  24.  
  25. =head1 SYNOPSIS
  26.  
  27.   use Net::DBus::Annotation qw(:call);
  28.  
  29.   my $object = $service->get_object("/org/example/systemMonitor");
  30.  
  31.   # Block until processes are listed
  32.   my $processes = $object->list_processes("someuser");
  33.  
  34.   # Just throw away list of processes, pretty pointless
  35.   # in this example, but useful if the method doesn't have
  36.   # a return value
  37.   $object->list_processes(dbus_call_noreply, "someuser");
  38.  
  39.   # List processes & get on with other work until
  40.   # the list is returned.
  41.   my $asyncreply = $object->list_processes(dbus_call_async, "someuser");
  42.  
  43.   ... some time later...
  44.   my $processes = $asyncreply->get_data;
  45.  
  46. =head1 DESCRIPTION
  47.  
  48. This module provides a number of annotations which will be useful
  49. when dealing with the DBus APIs. There are annotations for switching
  50. remote calls between sync, async and no-reply mode. More annotations
  51. may be added over time.
  52.  
  53. =head1 METHODS
  54.  
  55. =over 4
  56.  
  57. =cut
  58.  
  59. package Net::DBus::Annotation;
  60.  
  61. use strict;
  62. use warnings;
  63.  
  64. our $CALL_SYNC = "sync";
  65. our $CALL_ASYNC = "async";
  66. our $CALL_NOREPLY = "noreply";
  67.  
  68. bless \$CALL_SYNC, __PACKAGE__;
  69. bless \$CALL_ASYNC, __PACKAGE__;
  70. bless \$CALL_NOREPLY, __PACKAGE__;
  71.  
  72. require Exporter;
  73.  
  74. our @ISA = qw(Exporter);
  75. our @EXPORT_OK = qw(dbus_call_sync dbus_call_async dbus_call_noreply);
  76. our %EXPORT_TAGS = (call => [qw(dbus_call_sync dbus_call_async dbus_call_noreply)]);
  77.  
  78. =item dbus_call_sync
  79.  
  80. Requests that a method call be performed synchronously, waiting
  81. for the reply or error return to be received before continuing.
  82.  
  83. =cut
  84.  
  85. sub dbus_call_sync() {
  86.     return \$CALL_SYNC;
  87. }
  88.  
  89.  
  90. =item dbus_call_async
  91.  
  92. Requests that a method call be performed a-synchronously, returning
  93. a pending call object, which will collect the reply when it eventually
  94. arrives.
  95.  
  96. =cut
  97.  
  98. sub dbus_call_async() {
  99.     return \$CALL_ASYNC;
  100. }
  101.  
  102. =item dbus_call_noreply
  103.  
  104. Requests that a method call be performed a-synchronously, discarding
  105. any possible reply or error message.
  106.  
  107. =cut
  108.  
  109. sub dbus_call_noreply() {
  110.     return \$CALL_NOREPLY;
  111. }
  112.  
  113. 1;
  114.  
  115. =pod
  116.  
  117. =back
  118.  
  119. =head1 AUTHOR
  120.  
  121. Daniel Berrange <dan@berrange.com>
  122.  
  123. =head1 COPYRIGHT
  124.  
  125. Copright (C) 2006, Daniel Berrange.
  126.  
  127. =head1 SEE ALSO
  128.  
  129. L<Net::DBus>, L<Net::DBus::RemoteObject>
  130.  
  131. =cut
  132.